docs: state the TLS contract E39 is built against - #783

The contract page moves first, ahead of the code, because it is what the rest
of E39 is measured against. What each adapter actually does stays on its own
page and moves with the pull request that changes it.

Peer authorisation becomes two alternatives rather than one requirement. A
trust anchor or a pinned fingerprint authorises a peer, and a stream needs at
least one; supplying both means both must pass, which RFC 5425 6.1 calls the
recommended default. The old trust-anchor obligation could not coexist with
the fingerprint obligation on the same page, because 4.2.1 says a certificate
matched by fingerprint can be self-signed and needs no path validation.

The fingerprint obligation gains the spec it was missing: the 4.2.2 form, the
hyphenated IANA labels, sha-256 and sha-1 both accepted, a list rather than a
single value so a fleet can cross a certificate renewal, and a configured pin
matching nothing refuses the connection whatever the chain says. A configured
fingerprint also counts as declaring the peer identity, so it suppresses the
unidentified-peer report a missing name would otherwise raise.

"Report an unusable certificate, and keep delivering" is deleted rather than
softened. RFC 5280 6.1 makes validity an input to path validation, so a
certificate outside its dates does not chain, and the page previously listed
three things that stop delivery, excluded validity from them, then contradicted
itself. Revocation checking is declined here, which leaves the validity period
as the only mechanism by which a certificate ever stops being accepted; the
revocation section now says so. What was a proposed behaviour change becomes a
reporting change, and 731 is rescoped to naming the check that refused a
connection.

Credential custody is stated as an obligation for the first time: material is
obtained when a connection is made and released when it closes, so an
integrator can hold it in a secure element and have it in RAM only while
connecting. The limit is stated with it, since every TLS library keeps the
parsed key for the session and no stream can change that.

Session resumption gains a section for the second 4.2.3 SHOULD, which nothing
had tabulated. No shipped stream resumes, so it is met by construction, and
saying so stops a later refactor making it quietly false.

Both platform pages get their divergence lists completed against the contract:
fingerprints, the unnamed refusal reason, and credential sourcing are added,
and the expired-certificate entry is deleted from both as no longer a
divergence. The compliance matrix moves 4.2.1 server to Partial, adds the
resumption row, and the RFC 5425 count goes to 21.

Em dashes in these pages become hyphens, and CLAUDE.md's rule is corrected to
match: it previously exempted docs/ entirely. A dash left at the start of a
line by a hard wrap stays, because a hyphen there is a list marker.

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

…latforms

Review findings, and two of them are misreadings of RFC 5425 that were about
to be asserted on a page assessors read.

RFC 5425 6.1 does not name trust-anchor validation plus fingerprint matching
as the recommended default. Read against the text, it says the threats are
mitigated only if both the transport sender and the transport receiver are
authenticated and authorised, by one of 5.1 or 5.2, and contrasts that with
the unauthenticated policies of 5.3 to 5.5. It is about both endpoints, not
about combining both methods. Requiring both where an integrator supplied both
is this contract's choice and is now stated as one.

RFC 5425 4.2.3 recommends that a resumed session's parameters be checked; it
does not require it. The page said requires. It now says the RFC recommends
and this contract requires, which is the stronger claim and the true one.

The page also contradicted itself on when a configuration with neither trust
anchors nor fingerprints is rejected: create time in one section, connection
time in another. Trust anchors are obtained per connection, so a stream cannot
know at create time what its credential source will yield. The check is stated
once, at connection time, and the trust-anchor section points at it.

"Where this stands" stops describing what each platform does. It listed
behaviour that belongs on a platform page, and in one case listed it wrongly:
credential retention differs between the shipped adapters rather than being
common to them. It is now a table of which obligations have a platform short
of them and what tracks each, with the detail left to the pages that can state
it correctly. The compliance matrix loses the same kind of detail from its
resumption row.

The claim that validity is the only mechanism by which a certificate stops
being accepted is narrowed: chain, fingerprint and identity checks reject
certificates too, but they reject the same certificate today as yesterday.
Validity is the only check whose answer changes with time, which is the point
being made about declining revocation.

The Mbed TLS page separates two lifetimes it had been conflating. The handle
objects must stay addressable for as long as the stream might connect; the
parsed material inside them only while a connection is open. The rotation
sequence follows from the second, and the page now says the adapter never
announces that window, which is the gap the epic records.

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

A security review of the contract found the custody obligation claimed more
than the design can deliver, in the paragraph most likely to be read by
someone assessing the library.

The claim was that material exists in RAM only while a connection is being
established. It does not. It exists for the whole connection, and a connection
opens on the first record and closes only on a send failure, a destination
change, an explicit Disconnect, or destroy. On a device that logs steadily
that is the device's uptime. The private key is needed once, to sign during
the handshake, and is retained for the rest of the connection because neither
TLS library offers a client a way to hand it back. The page said the opposite
and then conceded it eleven lines later.

How much the release announcement buys also depends on the credential source,
which the contract cannot settle. A source that hands over a pointer to
material the integrator already holds parsed has nothing to release; one that
parses on demand and wipes on release does. The obligation now says so and
sends the reader to the platform page.

What the obligation is actually worth is stated instead: the stream announces
when it has finished with the material, so replacing it is no longer a
use-after-free the integrator has to sequence by hand, and where the key must
not be in application memory at all, that is a property of the source rather
than of the window.

A new obligation states the connection lifetime outright and names
SolidSyslogSender_Disconnect as the lever that bounds it, since that is the
only thing that actually shortens the exposure and an integrator asking the
question deserves the answer on the page. It is the same lever RFC 5425 4.4
wants for a connection expected to carry no more messages, so the compliance
row now answers all three of that section's requirements rather than only
close_notify.

Two gaps in the fingerprint obligation are closed. A pin excuses the chain but
not the clock: an expired pinned certificate is refused in fingerprint-only
mode exactly as anywhere else, which is worth stating because both backends
express that mode as a verification callback and one that overrides every
result rather than the chain result silently disables expiry checking. And
pinning makes the collector's expiry a fleet-wide event, so the page now
carries the RFC 5280 4.1.2.5 remedy and the overlap-pinning practice next to
the rule that creates the problem.

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

The contract page said what any TLS Stream must do and then, at the bottom,
what the shipped platforms currently do not. Both platform pages already carry
the second thing, entry by entry, with the issue tracking each. Keeping a
summary alongside them meant every change to an adapter had to be written in
two places, and the review of the previous commit found it written wrongly in
one: the summary claimed both platforms retain credentials after disconnect
when only one does.

So the section goes. The page states obligations; a platform page states where
that platform falls short of them. Its opening paragraph already sends the
reader there, and the capability matrix already says which platform fills the
role.

Two other corrections, both introduced by the previous commit.

The fingerprint obligation described how both backends implement
fingerprint-only mode. That is platform detail on a page that must not carry
any, and it asserted an implementation the compliance matrix records as absent.
The obligation stands - a pin excuses the chain, not the clock - and now says
why the two checks are independent rather than how an adapter wires them. The
implementation hazard is recorded on the issue that will implement it.

A sentence about credential sources read "already holds parted", which is not a
word.

The compliance matrix names SolidSyslogSender_Disconnect in full where it had
been shortened to a verb. The CI gate for this only fires on identifiers
containing an underscore, so it did not catch it.

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

The row said the section "requires both authorisation methods", which reads as
though a conforming deployment has to configure path validation and fingerprint
matching together. It requires an implementation to support both; which one a
deployment uses is its own choice, and docs/tls.md states them as alternatives.

The distinction matters on this row in particular. An assessor reads the
compliance matrix as a claim about the standard rather than about us, and this
is the second time in this branch that a 5425 requirement has been written
stronger than the RFC makes it - 6.1 was corrected two commits ago for saying
the RFC named the combination as its recommended default.

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>